Configuring SequeLink^® Server for DB2 on z/OS

NOTE: SequeLink DB2 services for z/OS must be created, started, stopped, and deleted locally using the SequeLink Manager for z/OS. See "Configuring SequeLink® Services Using the SequeLink® Manager for z/OS" for more information about creating and managing SequeLink services on z/OS.

Configuring the SequeLink^® Service for DB2 with the RRSAF Attachment

NOTE: We highly recommend that you use the ThreadPool connection model, which requires the RRSAF attachment. This setting allows you to have a large number of connections.

To configure a server using the DB2 RRSAF attachment:

Type S beside the Global Settings node for the server; then, press ENTER.
In the AttributeList panel, type C next to the MVSGlobalDB2Attachment service attribute. The service attribute panel appears.





Type / next to RRSAF to select it; then, press ENTER.

Configuring the DB2 environment for SequeLink Server involves:

"Binding the SequeLink® Package"
"Granting Access to the SequeLink® Server Package"
"Granting Cancel Thread Authorization to the SequeLink® Server"

Binding the SequeLink® Package

The server-specific CNTL library contains generated BIND jobs to bind the SequeLink DBRMs into packages.

Because SequeLink Server for DB2 can change isolation level dynamically, each DBRM is bound into a package using a different isolation level for each package. The collection ID name of each package is created by concatenating the DB2 collection prefix and the DB2 collection suffix as shown in Table 15-1.

Table 15-1. Isolation Levels of SequeLink DBRMs

Data Source Transaction Isolation	Data Source DB2 Collection Prefix	Data Source DB2 Collection Suffix	Collection ID	Isolation
Uncommitted	SLD600	U	SLD600_U	UR
Committed	SLD600	S	SLD600_S	CS
RepeatableRead	SLD600	T	SLD600_T	RS
Serializable	SLD600	R	SLD600_R	RR
NOTE: The collection prefix is set when you create the SequeLink data source (SequeLink service attribute DataSourceDB2CollectionPrefix). The collection suffix is set when you configure the transaction isolation level of the data source (SequeLink service attribute DataSourceTransactionIsolation). See "SequeLink® Service Attributes" for a list of SequeLink service attributes.

Granting Access to the SequeLink^® Server Package

Grant access to the SequeLink Server package for all users that will be connecting to the SequeLink Server. When granting access to the SequeLink package, remember to include the user ID associated with the SequeLink Server for each DB2 subsystem to which the SequeLink Server will connect. To grant access to the SequeLink Server package for all users, you can use the following SQL statement:

GRANT EXECUTE ON PACKAGE collection-id.* TO PUBLIC 

where collection-id.* is a collection-id used in the SequeLink bind job. See Table 15-1 for the names of possible collection-ids.

Granting Cancel Thread Authorization to the SequeLink_® Server

SequeLink automatically correlates output from DB2 with information from Connect ADO. This means that the SequeLink administrator has more control over the SequeLink sessions, and can take action without spending time to investigate why a killed session does not end.

To request the DB2 database to cancel a DB2 Thread, use the DB2 IFI call interface to route a -CANCEL THREAD(token) command to DB2. Connect ADO only requests canceling a DB2 Thread which is owned by it. DB2 threads owned by any other application are never canceled.

NOTE: This enhancement is not supported for the CAF attachment.

To enable this feature, define one of the following DB2 authorizations for the USERID that represents the SequeLink Server address space:
SYSOPR
SYSCTRL
SYSADM

Refer to your DB2 documentation for more information about the DB2 "COMMAND REFERENCE" -CANCEL THREAD(DB2) command.

Regenerate the JCL and run the bind job.

Configuring the SequeLink^® Service for DB2 with the CAF Attachment

If you cannot use the DB2 RRSAF attachment, you must change additional configuration settings.

To configure a server using the DB2 CAF attachment:

Type S beside the Global Settings node for the server; then, press ENTER.
In the AttributeList panel, type C next to the MVSGlobalDB2Attachment service attribute. The service attribute panel appears.





Type / next to CAF to select it; then, press ENTER.

NOTE: Selecting CAF as the value for MVSGlobalDB2Attachment implies that a DB2 plan (MVSDataSourceDB2Plan) is required. The MVSDataSourceDB2Plan service attribute is set to SLD600PL by default, but the value can be changed.

In the management tree of the SequeLink Service, expand the nodes. Type / next to the Advanced node; then, press ENTER. The AttributeList panel is displayed.





Type S beside the attribute you want to change; then, press ENTER. The Attribute Display window appears with the cursor positioned at the Value field of the attribute.
Type the new values of the following attributes; then, press ENTER:
Change ServiceConnectionModel to Thread/Connection
Decrease ServiceMaxSessions to 250
Increase ServiceMaxThreads to 256

You are returned to the AttributeList panel, and the attribute values, if valid, are changed.

Press F3 to return to the server management tree.

Configuring the DB2 environment for SequeLink Server involves:

"Binding the SequeLink® Package"
"Granting Access to the SequeLink® Server Package"
"Binding the SequeLink® Plan"
"Granting Access to the SequeLink® Server Plan"

Binding the SequeLink^® Package

The server-specific CNTL library contains generated BIND jobs to bind the SequeLink DBRMs into packages.

Because SequeLink Server for DB2 can change isolation level dynamically, each DBRM is bound into a package using a different isolation level for each package. The collection ID name of each package is created by concatenating the DB2 collection prefix and the DB2 collection suffix as shown in Table 15-2.

Table 15-2. Isolation Levels of SequeLink DBRMs 

Data Source Transaction Isolation	Data Source DB2 Collection Prefix	Data Source DB2 Collection Suffix	Collection ID	Isolation
Uncommitted	SLD600	U	SLD600_U	UR
Committed	SLD600	S	SLD600_S	CS
RepeatableRead	SLD600	T	SLD600_T	RS
Serializable	SLD600	R	SLD600_R	RR
NOTE: The collection prefix is set when you create the SequeLink data source (SequeLink service attribute DataSourceDB2CollectionPrefix). The collection suffix is set when you configure the transaction isolation level of the data source (SequeLink service attribute DataSourceTransactionIsolation). See "SequeLink® Service Attributes" for a list of SequeLink service attributes.

Granting Access to the SequeLink^® Server Package

Grant access to the SequeLink Server package for all users that will be connecting to the SequeLink Server. When granting access to the SequeLink package, remember to include the user ID associated with the SequeLink Server for each DB2 subsystem to which the SequeLink Server will connect. To grant access to the SequeLink Server package for all users, you can use the following SQL statement:

GRANT EXECUTE ON PACKAGE collection-id.* TO PUBLIC 

where collection-id.* is a collection-id used in the SequeLink bind job. See Table 15-2 for the names of possible collection-ids.

Binding the SequeLink^® Plan

The server-specific CNTL library contains a generated BIND job to bind the SequeLink Server packages into plans.

The SequeLink plan name is set when you create the SequeLink data source (SequeLink service attribute MVSDataSourceDB2Plan). For a list of SequeLink service attributes, refer to the SequeLink Installation Guide.

Granting Access to the SequeLink^® Server Plan

When you are setting up your server to use the CAF attachment, you must grant access to the SequeLink plan for all users who will connect to the SequeLink Server. When granting access to the SequeLink plan, remember to include the user ID associated with the SequeLink Server for each DB2 subsystem to which the SequeLink server will connect.

To grant access to the SequeLink plan for all users, take the following steps:

Use the following SQL statement:

GRANT EXECUTE ON PLAN planname TO PUBLIC

where planname is the name of the SequeLink plan.

Refer to your DB2 documentation for more information about the DB2 "COMMAND REFERENCE" -CANCEL THREAD(DB2) command.

Regenerate the JCL and run the bind job.

Using z/OS Workload Manager (WLM)

Workload Manager (WLM) manages workloads and optimizes throughput based on policies defined by the WLM administrator. A workload is a collection of service classes that are tracked and reported as a unit. WLM distributes the available computer resources to achieve the goals defined in the policy. You can define different performance goals and processing rules for different workloads. For example, you can assign priorities so that the workload for your Customer Orders department has a higher priority than the workloads for the Human Resources and Marketing departments, which do not require the same level of service.

The SequeLink Server for z/OS supports WLM by using enclaves. An enclave is a z/OS construct that serves as a unit of priority and accounting for a transaction. You define performance criteria for an enclave using service policies, which are a collection of performance goals and processing capacity rules. You can use service policies to define groups of service classes that can be used for workloads with similar performance requirements. For example, you can define a service class that requires an average response time, sets a high business importance, and uses a resource group that guarantees a minimum amount of CPU is granted even if the enclave does not meet the response time goal. For more information about defining service classes, refer to your IBM documentation.

When SequeLink is enabled for WLM and a client connection is made to the Server, an independent enclave is created and classification information is passed to WLM. See "z/OS Workload Manager (WLM) Classification" for more information.

This classification information allows the WLM administrator to define rules so that WLM can determine the "Service class" to be used for the enclave(s) created for this connection. Each enclave is managed separately according to its performance goal or performance group.

When the connection to the SequeLink Server ends, the CPU consumption of all of the enclaves for this connection is reported in the SMF record, if activated (see "Configuring SMF Accounting").

Configuring SequeLink® Server for Workload Management

The default setting MVSGlobalWLMEnclaves =NONE disables WLM support in the SequeLink Server for DB2 for z/OS. To enable WLM for a SequeLink Server, you must use one of the following settings for the MVSGlobalWLMEnclaves attribute:

MVSGlobalWLMEnclaves =CONNECTION. SequeLink creates a single WLM enclave for each new incoming client connection. This enclave exists for the duration of the connection. Because the enclave includes client think-time and network wait-time, it is not appropriate to define WLM velocity goals.
MVSGlobalWLMEnclaves=RPC. SequeLink creates a new WLM enclave for each SequeLink RPC (each network access to the SequeLink Server). This setting allows the WLM administrator to specify response time goals without regard to network wait time or client application processing time.

When MVSGlobalWLMEnclaves is set to either CONNECTION or RPC, SequeLink Server for DB2 for z/OS connects during startup to WLM as a Workmanager of type VAI. The instance name used on the initial connection to WLM is the value of the MVSGlobalSubSysID attribute (see "MVSGlobalSubSysID").

Additionally you must define classification rules in WLM. "z/OS Workload Manager (WLM) Classification" gives an overview of ALL information passed to WLM by SequeLink. You can select the criteria you need to classify one or more connections to a Service Class.

SequeLink Cluster in a Sysplex

To achieve high availability, ensure a consistent response time, and provide a future path of growth for your applications, IBM introduced the Sysplex cluster technology. Beginning with OS/390 V2R7, the TCP/IP stack changed to fully exploit this new technology, and now supports TCP/IP connection distribution in a Sysplex. Three different implementation models are available:

Sysplex distributor
Domain Name System (DNS)/Workload Manager (WLM)
Network dispatcher

All three implementations use multiple Server images distributed over your Sysplex cluster, which appear to your clients as a single server application. New incoming TCP/IP client connections are then distributed over the server images based on workload and availability information.

Not all solutions require support from Sequelink Server for DB2 for z/OS. The Sysplex distributor and network dispatcher models can be implemented without any specific interaction with Sequelink. The DNS/WLM solution requires Sequelink to register to WLM during startup of the Server.

The MVSGlobalClustername attribute has been added to support the DNS/WLM implementation model (see "MVSGlobalClustername" for more information). All servers on the different clusters must use the same clustername to register to WLM and thus appear as a single application to your clients. DNS regularly queries WLM and based on this information, routes new TCP/IP connection requests for this clustername to the appropriate server image.

The IBM Redbook, TCP/IP in a Sysplex, document number SG24-5235-02 explains in detail the different implementation models. If you are considering the use of TCP/IP in a Sysplex environment, this book is required reading.

Configuring SMF Accounting

When SMF accounting is enabled, records are written to the active SMF data set using the SMF record ID at the end of each client connection. SMF accounting is enabled by default and the SMF record ID is configured using the GlobalSMFRecordType attribute, which is a Global Settings attribute of the SequeLink Server. If you do not want to use the SMF accounting facility, you can turn it off by deleting the GlobalSMFRecordType attribute.

SMF records contain statistical data that can be used to track information for charge-back systems. The following data is provided for each database session:

Job/STC name of the server
Client logon ID
Internal Thread ID assigned by SequeLink Server
Mapped user ID
Session start/end times
Number of packets and bytes received/sent
Total CPU consumption
Service name
Application loadmodule name
Network node name of the client
DataSource name
Thread abend/abort information
Abend code
Number of SQL calls, checkpoint calls, and DB2 OPEN calls
Number of records switched for ReadTimeout
Number of records switched for Max RPC
Accumulated CPU consumption and elapsed time for SQL calls
WLM ServiceClass

The following example shows a typical SMF record. A sample job (RUNSMF) to print out the SMF records is provided in the SequeLink_HLQ.CNTL library.

*********************************************************************** 
*                         SMF RECORD HEADER                                                               
*********************************************************************** 
SMFRECORD   DS     0F 
SMFRECLEN   DS     H        RECORD LENGTH 
SMFDESC     DS     H        DESCRIPTOR (MUST BE ZERO) 
SMFSYS      DS     X        SYSTEM INDICATOR (SET TO ZERO) 
SMFTYPE     DS     X        Record type (MVSGlobalSMFRecordType) 
SMFTIME     DS     AL4      CURRENT TIME 
SMFDATE     DS     AL4      CURRENT DATE 
SMFSID      DS     CL4      SYSTEM ID 
SMFSUBS     DS     CL4      SERVER SUBSYSTEMID OR BLANKS 
SMFHDRLEN EQU   *-SMFRECORD HEADERLENGTH 
SMFUSER     DS     0X       START OF SUBTYPE FIELD(S) 
* 
*  VARIABLE USER FIELDS START HERE 
* 
********************************************************************** 
* SUBTYPE X'0001' - SESSION ACCOUNTING RECORD                        *  
********************************************************************** 
@ACCTREC  DSCET 
@ACCTLEN    DS    XL2       Accounting record length 
@ACCTTYP    DS    XL2       Accounting record subtype (X'0001') 
* 
@ACCTJNM  DS   CL8      Serv STC/JOB/Name 
@ACCTUID    DS    CL8       RACF Userid connected to thread 
@ACCTTID    DS    CL8       Thread ID 
@ACCTAPL    DS    CL8       Application name 
@ACCTSVC    DS    CL8       Service name 
* 
@ACCTNOD    DS    CL16      Client node name (TCP/IP address) 
@ACCTCNT    DS    F         Message count 
@ACCTBIN    DS    F         Total Input packet byte count 
@ACCTBOT    DS    F         Total Output packet byte count 
* 
* Session Start - Time and date (SMF header type) 
* 
@ACCTBGT    DS    F      Time since Midnight in 100th of second 
@ACCTBGD    DS    PL4    Date in 0CYYDDDF format -  C is 1 if year is 20YY, 
                         is 0 if 19YY     
* 
*  Session Ending - Time and date  ( SMF header type ) 
* 
@ACCTENT    DS    F      Time since Midnight in 100th of second 
@ACCTEND    DS    PL4    Date in 0CYYDDDF format 
* 
@ACCTCPU    DS    F      CPU TIME used - measured in 100th of a second 
* 
@ACCTERR    DS    X         
ACCTABND    EQU   1      Thread abended - abend code in @ACCTABN 
ACCTABIT    EQU   2      Idle Timeout  
ACCTABOP    EQU   4      Aborted by Operator 
ACCTMXCP    EQU   8      Aborted for MaxCPU   
*	 
@ACCTABN    DS    XL3    Left  12 bits - Systemabend code in Hex 
*                        Right 12 bit  - Userabend   code in Hex 
* 
@ACCTDBC    DS    F      Database Calls - count 
@ACCTDBO    DS    F      Database Opens - count 
@ACCTCKP    DS    F      Database Checkpoints - count 
@ACCTSQC    DS    F      Accum SQL CPU time in 100th of seconds 
@ACCTSQE    DS    F      Accum SQL Elapsed time in 100th of seconds 
@ACCTWSC    DS    CL8    WLM ServiceClass or blanks 
@ACCTUID2   DS    CL8    Mapped Userid - Primary authid DB2 
@ACCTDSRC   DS    CL64   DataSource Name 
@ACCTSWTO   DS    F      Count - switched for ReadTimeout 
@ACCTSWMR   DS    F      Count - switched for Max RPC 
@ACCTLTH  EQU  *-@ACCTREC  SUBTYPE LENGTH 

If you have your own version of an SMF processing program you can check the accounting record length if you need to differentiate your SMF records between the previous version layout and the new SMF record layout. For example:

@ACCTLEN DS    XL2           Accounting record length 

Adding a UID Map to the SequeLink^® Service

UID mapping is the optional mapping of user IDs to alternate user IDs using a UID map. You can use UID mapping to prevent users from updating DB2 tables using commonly available tools, such as QMF or SPUFI, while preserving their ability to update DB2 tables using SequeLink. A UID map is an independent entity in the SequeLink configuration and can be specified at the level of a SequeLink service or/and at the level of a SequeLink Server data source. (See "MVSServiceUIDMap" for more information.)

UID mapping is required when ServiceAuthMethods=Anonymous.

You can specify a UID map for a SequeLink service and another UID map for a SequeLink Server data source. See "Using UID Mapping" for more information about using UID maps.

To add a UID map:

From the server management tree, type A beside the UID Maps node to add a UID map to the SequeLink Server; then, press ENTER. The Add UID Map panel appears.





Provide the following information; then, press ENTER.

UID Map Name: Type the name of the UID map to add to the SequeLink Server. The corresponding service attribute is MVSUIDMap.

Default access: Choose one of the following options for the default behavior of the UID map you are adding by typing:

PERMIT. If the user ID cannot be found in the UID map, the connection request is accepted. The userid is passed to DB2 as the primary authid.
DENY. If the user ID cannot be found in the UID map, the connection request is refused.

The corresponding service attribute is MVSUIDDefaultAccess.

Description: Type a description of the UID map.

The corresponding service attribute is MVSUIDMapDescription.

If the UID map was added successfully, a message appears to confirm it.
To add mapping entries to the UID map, type S beside the UID map; then, press ENTER. The AttributeList panel appears.





Type Add at the command prompt; then, press ENTER. A panel appears allowing you to specify a UID mapping entry for the MVSUID attribute.





Specify a value for the MVSUID attribute using the format user=mapped_user or *=mapped_user where:
user is a valid user or user group for the z/OS security system.
* represents any user. This value is required when ServiceAuthMethods=Anonymous.
mapped_user is a valid DB2 authorization ID.

Then, press ENTER.

You are returned to the AttributeList panel. Add another MVSUID entry or press F3 to return to the server management tree.
To configure a SequeLink service to use the UID map, set the MVSServiceUIDMap service attribute and/or MVSDataSourceUIDap attribute.

NOTE: You must restart the SequeLink Server before this change will take effect.

See "Using UID Mapping" for more information about using UID maps.